INTRODUCTION

   This file describes how other programs can remote control the STinG Dialer. 
   The Dialer can be requested to either dial, or hangup, a connection. The 
   requesting program (the requester) is told about success or the error that 
   occured. During remote controled dialing or hangup no user interaction with 
   the Dialer is required, i.e. no alerts will pop up. The requester basically 
   sends a message to the Dialer that tells the Dialer about the script file 
   to be used, and the maximum number of attempts that the Dailer is allowed 
   to do. A success or an error message is returned, the error message contains 
   a code that identifies the error. Requesting a hangup works likewise, how-
   ever, no parameters are to be passed in that case.

   With STinG a local area network (LAN) can be operated. Often there will be 
   a machine with a modem that is able to dial up a modem (phone) connection 
   to the outside world's Internet. Murphy's law says that whenever you need 
   an urgent connection to the Internet, and the modem is on hook, you'll be 
   working on the machine that is farthest from the one with the modem. To work 
   around Murphy's law, the Dialer's remote control facility uses UDP packets 
   for the request messages, so that any computer in the LAN can launch the 
   dial-up procedure.

   Since clairvoyance is not one of the usual client's abilities, it must be
   told where to send the UDP packets to (i.e. the address of the machine 
   running the Dialer). To that end, each STinG installation should have a 
   network environment entry (i.e. a line in DEFAULT.CFG) of the general form
   `DIALER=address', where `address' is either a dotted quad IP address, or
   the fully qualified domain name of the machine running the Dialer.


PROTOCOL

   Any client that wishes to remote control the Dialer first calls the STinG 
   function getvstr() to find out the value of the configuration variable 
   "DIALER". The resulting string is the IP address or the fully qualified 
   domain name of the machine the Dialer is running on. Now a UDP message 
   is sent to the specified machine, the port is defined in REM_CTRL.H.

   Each message consist of a number of bytes, specifying the meaning of the 
   message, and a few additional parameters. The first two bytes form an 
   integer saying if a dial-up (IP_DIAL_REQUEST) or a hang-up (IP_DIAL_HANGUP)
   is requested. Nothing more is required for a hang-up request. For dial-up
   requests the maximum number of attempts, and the dial script to be used,
   must be specified too. The integer made of the third and the fourth byte
   specifies the maximum number of dial-up attempts. Starting with the fifth
   byte, the name of the dial script, terminated by a zero byte, follows.

   After sending the message the requester should anticipate a UDP message 
   from the Dialer. This can be either IP_DIAL_DONE or IP_DIAL_ERROR. In case 
   of IP_DIAL_ERROR the third and the fourth byte form the actual error code.
   The error codes can be
   
        for  IP_DIAL_REQUEST  :
               IP_IN_PROGRESS       The Dialer is already dialing.
               IP_IS_CONNECTED      The Dialer already connected this port
                                    before.
               IP_SCR_NOT_FOUND     The Dialer had problems loading the 
                                    script file.
               IP_PORT_LOCKED       Port could not be opened, probably 
                                    because another program uses it.
               IP_MAX_EXCEEDED      The specified maximum number of redials 
                                    have been carried out.
               IP_FATAL_PROBLEM     The Dialer got a fatal error response
                                    from the modem.
               IP_USER_ABORT        The user aborted the dial process.
               IP_OPEN_FAILED       STinG refuses to accept the connection.

        for  IP_DIAL_HANGUP  :
               IP_IN_PROGRESS       During the dial process hangup requests
                                    cannot be processed.
               IP_OPEN_FAILED       Due to some strange reason the port
                                    could not be reopened.

   Note that if IP_OPEN_FAILED is responded to IP_DIAL_REQUEST, your modem
   is still off hook ! Thus the telephone company will start to charge money 
   unless IP_DIAL_HANGUP is send ! For all the other error codes the modem 
   is on hook afterwards. The same holds for any response to IP_DIAL_HANGUP.


EXAMPLE

   For an example look at the Pure C sample code DIALCTRL.C. It contains 
   a simple program that just implements the above discussed protocol for 
   requesting a dialup.


AUTHOR

   Any further questions or good ideas for extensions should be directed 
   to :

   Peter Rottengatter
   Kriegerstrasse 18
   30161 Hannover
   Germany

   perot@pallas.amp.uni-hannover.de